// 版权所有2010 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

package http

import (
	"io"
	"net/http/httptrace"
	"net/http/internal/ascii"
	"net/textproto"
	"sort"
	"strings"
	"sync"
	"time"

	"golang.org/x/net/http/httpguts"
)

// 头表示HTTP头中的键值对。
// 
// 密钥应为规范格式，由
// CanonicalHeaderKey返回。
type Header map[string][]string

// Add将密钥、值对添加到头中。
// 它附加到与键相关的任何现有值。
// 密钥不区分大小写；它被
// CanonicalHeaderKey规范化。
func (h Header) Add(key, value string) {
	textproto.MIMEHeader(h).Add(key, value)
}

// Set将与键关联的头条目设置为
// 单个元素值。它将替换与键关联的任何现有值
// 。密钥不区分大小写；这是
// 由textproto规范化。CanonicalTimeHeaderKey。
// 要使用非规范密钥，请直接分配给映射。
func (h Header) Set(key, value string) {
	textproto.MIMEHeader(h).Set(key, value)
}

// Get获取与给定键关联的第一个值。如果
// 没有与键关联的值，Get返回“”。
// 不区分大小写；文本原型。CanonicalTimeHeaderKey是
// 用于规范化提供的密钥。要使用非规范密钥，请直接访问地图。
func (h Header) Get(key string) string {
	return textproto.MIMEHeader(h).Get(key)
}

// Values返回与给定键关联的所有值。
// 不区分大小写；文本原型。CanonicalTimeHeaderKey是
// 用于规范化提供的密钥。要使用非规范
// 键，请直接访问地图。
// 返回的切片不是副本。
func (h Header) Values(key string) []string {
	return textproto.MIMEHeader(h).Values(key)
}

// get与get类似，但key必须已经是CanonicalHeaderKey格式。
func (h Header) get(key string) string {
	if v := h[key]; len(v) > 0 {
		return v[0]
	}
	return ""
}

// 报告h是否定义了提供的密钥，即使它是
// 设置为0长度切片。
func (h Header) has(key string) bool {
	_, ok := h[key]
	return ok
}

// Del删除与键关联的值。
// 密钥不区分大小写；它被
// CanonicalHeaderKey规范化。
func (h Header) Del(key string) {
	textproto.MIMEHeader(h).Del(key)
}

// Write以wire格式写入头。
func (h Header) Write(w io.Writer) error {
	return h.write(w, nil)
}

func (h Header) write(w io.Writer, trace *httptrace.ClientTrace) error {
	return h.writeSubset(w, nil, trace)
}

// 如果h为nil，克隆将返回h或nil的副本。
func (h Header) Clone() Header {
	if h == nil {
		return nil
	}

	// 查找值的总数。
	nv := 0
	for _, vv := range h {
		nv += len(vv)
	}
	sv := make([]string, nv) // 头的值的共享备份数组
	h2 := make(Header, len(h))
	for k, vv := range h {
		n := copy(sv, vv)
		h2[k] = sv[:n:n]
		sv = sv[n:]
	}
	return h2
}

var timeFormats = []string{
	TimeFormat,
	time.RFC850,
	time.ANSIC,
}

// ParseTime解析时间头（例如日期：header），
// 尝试HTTP/1.1:
// TimeFormat，time允许的三种格式中的每一种。RFC850，还有时间。安西奇。
func ParseTime(text string) (t time.Time, err error) {
	for _, layout := range timeFormats {
		t, err = time.Parse(layout, text)
		if err == nil {
			return
		}
	}
	return
}

var headerNewlineToSpace = strings.NewReplacer("\n", " ", "\r", " ")

// stringWriter在写入程序上实现写限制。
type stringWriter struct {
	w io.Writer
}

func (w stringWriter) WriteString(s string) (n int, err error) {
	return w.w.Write([]byte(s))
}

type keyValues struct {
	key    string
	values []string
}

// headerSorter实现排序。通过按键对[]keyValues 
// 进行排序来实现接口。它被用作一个指针，因此可以放入排序中。接口
// 未分配的接口值。
type headerSorter struct {
	kvs []keyValues
}

func (s *headerSorter) Len() int           { return len(s.kvs) }
func (s *headerSorter) Swap(i, j int)      { s.kvs[i], s.kvs[j] = s.kvs[j], s.kvs[i] }
func (s *headerSorter) Less(i, j int) bool { return s.kvs[i].key < s.kvs[j].key }

var headerSorterPool = sync.Pool{
	New: func() any { return new(headerSorter) },
}

// sortedKeyValues返回在返回的kvs中排序的h键
// slice。还将返回用于排序的headerSorter，因为可能是
// 返回headerSorterCache。
func (h Header) sortedKeyValues(exclude map[string]bool) (kvs []keyValues, hs *headerSorter) {
	hs = headerSorterPool.Get().(*headerSorter)
	if cap(hs.kvs) < len(h) {
		hs.kvs = make([]keyValues, 0, len(h))
	}
	kvs = hs.kvs[:0]
	for k, vv := range h {
		if !exclude[k] {
			kvs = append(kvs, keyValues{k, vv})
		}
	}
	hs.kvs = kvs
	sort.Sort(hs)
	return kvs, hs
}

// WriteSubset以wire格式写入头。
// 如果exclude不是nil，则不写入exclude[key]==true的键。
// 在检查排除映射之前，密钥没有标准化。这可能是个错误。但是，在
func (h Header) WriteSubset(w io.Writer, exclude map[string]bool) error {
	return h.writeSubset(w, exclude, nil)
}

func (h Header) writeSubset(w io.Writer, exclude map[string]bool, trace *httptrace.ClientTrace) error {
	ws, ok := w.(io.StringWriter)
	if !ok {
		ws = stringWriter{w}
	}
	kvs, sorter := h.sortedKeyValues(exclude)
	var formattedVals []string
	for _, kv := range kvs {
		if !httpguts.ValidHeaderFieldName(kv.key) {
			// 编写响应头的常见情况下，我们没有很好的
			// 方法将错误返回给服务器
			// 处理程序，所以只需删除无效的头即可。
			continue
		}
		for _, v := range kv.values {
			v = headerNewlineToSpace.Replace(v)
			v = textproto.TrimString(v)
			for _, s := range []string{kv.key, ": ", v, "\r\n"} {
				if _, err := ws.WriteString(s); err != nil {
					headerSorterPool.Put(sorter)
					return err
				}
			}
			if trace != nil && trace.WroteHeaderField != nil {
				formattedVals = append(formattedVals, v)
			}
		}
		if trace != nil && trace.WroteHeaderField != nil {
			trace.WroteHeaderField(kv.key, formattedVals)
			formattedVals = nil
		}
	}
	headerSorterPool.Put(sorter)
	return nil
}

// CanonicalHeaderKey返回
// 头键s的规范格式。规范化将第一个
// 字母和连字符后面的任何字母转换为大写；
// 其余部分转换为小写。例如，
// 用于“接受编码”的标准密钥是“接受编码”。
// 如果s包含空格或无效的头字段字节，则返回
// 而不进行修改。
func CanonicalHeaderKey(s string) string { return textproto.CanonicalMIMEHeaderKey(s) }

// hasToken报告令牌是否显示为v，ASCII 
// 不区分大小写，带空格或逗号边界。
// 令牌必须全部小写。
// v可能含有混合外壳。
func hasToken(v, token string) bool {
	if len(token) > len(v) || token == "" {
		return false
	}
	if v == token {
		return true
	}
	for sp := 0; sp <= len(v)-len(token); sp++ {
		// 检查第一个字符是否正确。
		// 标记是ASCII，因此只检查单个字节
		// 就足够了。如果第一个字节及其可能的
		// 位置。
		// ASCII大写等价物（b | 0x20）不匹配，我们将跳过这个可能的起始
		// 误报（“^”=>“~”）被EqualFold捕获。
		if b := v[sp]; b != token[0] && b|0x20 != token[0] {
			continue
		}
		// 检查起始pos是否位于有效的令牌边界上。
		if sp > 0 && !isTokenBoundary(v[sp-1]) {
			continue
		}
		// 检查结束pos是否位于有效的令牌边界上。
		if endPos := sp + len(token); endPos != len(v) && !isTokenBoundary(v[endPos]) {
			continue
		}
		if ascii.EqualFold(v[sp:sp+len(token)], token) {
			return true
		}
	}
	return false
}

func isTokenBoundary(b byte) bool {
	return b == ' ' || b == ',' || b == '\t'
}
